feat(compiler): add @strictExtends to require union variants to nominally extend the base type - #11780

Fixes #3900

Why

#2737 / #11771 added union Foo extends Base { ... }, and by design that clause is a structural constraint: any variant whose shape is assignable to Base satisfies it.

Emitters targeting languages without native unions (C#, Java, Go, ...) represent such a union as a polymorphic base type, and that representation only works if every variant actually derives from the base. A variant that merely happens to have the same shape cannot be emitted as a subclass.

@strictExtends is an opt in decorator that turns that requirement into a compile time error. It changes nothing for existing code and nothing about the default behaviour of #11771.

model Pet {
  name: string;
}
model Cat extends Pet {
  meow: boolean;
}
model Rock {
  name: string;
}

@strictExtends
union Pets extends Pet {
  cat: Cat, // ok: `Cat` extends `Pet`
  rock: Rock, // error: `Rock` has the same shape as `Pet` but doesn't extend it
}

Semantics

The base type must be a model, a scalar or an enum. Those are the only types that can be explicitly extended, so @strictExtends on a union whose base is another union, a tuple or unknown is an error rather than a silent no-op.

A union carries no value of its own, so the check is really a reachability question: is anything offending reachable from the variant through union edges? That framing is what makes cycles, empty unions and never fall out for free, and it keeps composition closed - a union that satisfies @strictExtends on its own is always usable as a variant of another one.

Implementation notes

• Validation runs from onGraphFinish. Anything earlier is observably wrong: a union that is part of a cycle is still being built when the decorated union finishes, which made the outcome depend on the declaration order of the other union''s variants. It also means a decorator applied later on the same union cannot invalidate the guarantee. Both cases have tests.
• That surfaced a pre-existing checker bug, fixed here in its own commit: postCheckValidators is drained once, at the end of checkProgram, so an onGraphFinish validator registered for a type created after that (a clone a mutator produces during $onValidate, for example) was registered and never run. The checker now runs it as soon as the type is finished. @typespec/http is the other onGraphFinish consumer and had the same latent hole. Detecting this in the decorator via program.currentStage is not enough: the stage stays "checking" when the checker reported errors, which is exactly the state a language server program is left in.
• The walk is a plain reachability traversal with a visited set, so it is linear in the size of the union graph including cycles. There are regression tests at depth 30 for both an acyclic and a cyclic diamond; an earlier memoization scheme that disabled reuse around cycles took ~8s at depth 24.
• A variant that is not even assignable to the base type gets both unassignable and strict-extends-variant. Suppressing the second one required assuming the checker had already reported the first, which is not true once a decorator rewrites the variants.
• Applying the decorator more than once, directly or through @@strictExtends, validates the union once.

Open design questions

1. Error or warning? Currently an error. A warning would let a spec adopt the decorator incrementally.
2. Should this be a decorator at all, or syntax (for example union Foo extends strict Base)? A decorator keeps feat(compiler): add extends base type clause for unions #11771 untouched and is easy to remove if the design lands differently.
3. Should the base type be allowed to be an enum? It is allowed here for symmetry, but enum member assignability is already nominal, so it adds no constraint beyond rejecting non members.
4. Post-check onGraphFinish is weaker than at graph finish. For a type created after checking it can only see the graph as it exists when that type is finished, so it cannot observe relationships attached later. That is disclosed on DecoratorValidatorCallbacks.onGraphFinish; giving it true graph-finish semantics would need an explicit "dynamic graph completed" operation, which felt out of scope here.
5. Should emitters get a public helper (isStrictExtends(program, union)) instead of each one re-deriving it? The state is tracked internally already.
6. Double diagnostic: is unassignable + strict-extends-variant on the same variant acceptable, or should the strict one be suppressed at the cost of the soundness hole described above?

Validation

• tsc -p tsconfig.build.json --noEmit clean
• 4237 compiler tests pass, including 36 new @strictExtends tests
• @typespec/openapi3 2578 tests pass, @typespec/http 21/21 files pass
• pnpm lint clean, prettier clean
• Every non obvious test was mutation verified: reverting to onTargetFinish, restoring the assignability suppression, removing the duplicate application guard, removing memoization and disabling reuse across cycles each make exactly the intended tests fail.

Review history

Three adversarial review passes were run against this change. The first found 6 issues (silent bypass for non model base types, exponential walk, decorator ordering, composition not closed, missing export, diagnostic quality); the second found 3 more (declaration order dependence, the assignability suppression bypass, exponential behaviour on cyclic graphs) plus duplicate diagnostics on repeated application. The third found that onGraphFinish validators registered after checking never ran, which is the checker fix above; the fourth found nothing further. All are fixed and covered by tests.

--generated by Copilot